access-config-utils

About

A Python package providing various utilities to work with configurations for the models developed at ACCESS-NRI.

Key Features

Parsers:

• Various parsers for configuration files used across ACCESS-NRI models
• Support for round-trip parsing, preserving comments and formatting
• Simple API

Documentation

Coming soon.

Installation

Using pip

You can install the latest release directly from PyPI:

pip install access-config-utils

From source

If you prefer to install from source:

git clone https://github.com/ACCESS-NRI/access-config-utils.git
cd access-config-utils
pip install .

Usage

Configuration files parsers

Here is a simple example of how to parse a text and modify its contents.

To parse some text, one just needs to call the parse function of the appropriate parser:

from access.config import FortranNMLParser

text = '''&data_nml
 parameterA = 1
 parameterB = 'abc'
/'''

config = FortranNMLParser().parse(text)
print(config)

&data_nml
parameterA = 1
parameterB = 'abc'
/

The parsed content can then be modified like a Python dict. Everything not touched — comments, blank lines, spacing — is reproduced exactly:

config["data_nml"]["parameterA"] = 2
print(config)

&data_nml
parameterA = 2
parameterB = 'abc'
/

New keys can be added too, and are written in the style of their neighbours. Each value is written in whichever notation the format uses, so a bool becomes a Fortran logical here:

config["data_nml"]["parameterC"] = True
config["data_nml"]["parameterD"] = [1, 2, 3]
config["new_nml"] = {"parameterE": "def"}
print(config)

&data_nml
parameterA = 2
parameterB = 'abc'
parameterC = .true.
parameterD = 1, 2, 3
/
&new_nml
parameterE = "def"
/

A value the format cannot express raises UnsupportedEntryError rather than writing a file that no longer means what the dict says — for instance None in a format with no valueless assignment, or a string containing a space in one with no quoted-string syntax.

Two caveats on the dict and list behaviour. Operations that would add, remove or reorder the elements of a list value (append, extend, insert, pop, sort, …) raise NotImplementedError, because each element is tied to the place it came from in the file; assign a whole new list instead. And replacing an existing block wholesale raises SyntaxError — a block can be created and edited, but not swapped out.

Development installation

If you intend to contribute or modify the package, it is recommended to work inside a virtual environment.

1. Create and activate a virtual environment

# Create a virtual environment
python3 -m venv .venv

# Activate the virtual environment
source .venv/bin/activate

2. Install in editable mode with development and test dependencies

pip install -e ".[devel,test]"

This will install the package in editable mode, meaning changes to the source code are reflected immediately without reinstallation. Development dependencies such as testing tools will also be installed.

3. Run the test suite

pytest

Contributing

Contributions are welcome! Please open an issue or submit a pull request if you’d like to add features, fix bugs, or improve documentation.

For significant contributions, we recommend discussing proposed changes in an issue before opening a pull request.

License

This project is licensed under the Apache 2.0 License.