crossconfig 0.0.4

Simple cross-platform settings/configuration package.

CrossConfig

This package provides a simple cross-platform configuration system for storing, loading, and updating settings for an application or project. This package uses only standard library modules, and it encodes settings in JSON.

Installation

pip install crossconfig

Status

Issues can be tracked here. Changelog can be found here

Usage

Usage is simple: import the get_config function, and call it with the name of your application. This will return a config object that you can use to load, save, and get settings. If you want to use a portable config, pass portable=True to the function, and the settings file will be stored in the current working directory instead of the user's home directory.

Full documentation generated by autodox can be found here.

Example

from crossconfig import get_config

# choose whether to load the config for the current user or a portable config
portable = True

# load the config
config = get_config("my_app_name", portable=portable)
config.load()

# get a path for a subdirectory
subdir_path = config.path("subdir")

# set a setting
config.set("my_setting", "my_value")

# save and reload the config
config.save()
[config.unset(key) for key in config.list()]
assert len(config.list()) == 0
config.load()

# get a setting
assert config.get("my_setting") == "my_value"

# unset a setting
config.unset("my_setting")

# save the config
config.save()

Event Notifications

The config object supports a publish/subscribe event system for reacting to configuration changes.

Basic Event Subscription

You can subscribe to automatic events that fire when settings are set or unset:

from crossconfig import get_config

config = get_config("my_app")

# Define a listener function
def on_setting_change(event, data):
    print(f"Event: {event}, Data: {data}")

# Subscribe to a specific key being set/unset
config.subscribe("set_theme", on_setting_change)
config.subscribe("unset_theme", on_setting_change)

# Set/unset a setting - this will trigger the listener
config.set("theme", "dark")  # Prints: Event: set_theme, Data: dark
config.unset("theme")  # Prints: Event: unset_theme, Data: None

Wildcard Subscriptions

Wildcard patterns let you subscribe to multiple events at once:

config = get_config("my_app")

# Subscribe to ALL set/unset events
config.subscribe("set_*", lambda e, d: print(f"Setting changed: {e}"))
config.subscribe("unset_*", lambda e, d: print(f"Setting removed: {e}"))

# Subscribe to ANY event on a specific key (set or unset)
config.subscribe("*_theme", lambda e, d: print(f"Theme changed: {e}"))

# Subscribe to ALL events (wildcard of wildcards)
config.subscribe("*", lambda e, d: print(f"Any event: {e}"))

config.set("theme", "dark")
config.set("language", "en")
config.unset("theme")

Manual Event Publishing & Unsubscribing

You can publish custom events and remove subscriptions:

config = get_config("my_app")

listener = lambda e, d: print(f"Event: {e}, Data: {d}")

# Subscribe to a custom event
config.subscribe("custom_event", listener)

# Publish a custom event
config.publish("custom_event", {"message": "hello"})
# Prints: Event: custom_event, Data: {'message': 'hello'}

# Unsubscribe the listener
config.unsubscribe("custom_event", listener)

# Publishing now won't trigger the listener
config.publish("custom_event", {"message": "hello again"})

Notes

• The load method will return a JSON decode error if the config file is not valid JSON. If it loads successfully, it will return None.
• There is no lock for multi-threaded access to the config object or file. Calling save or load in a multi-threaded environment may result in a race condition.
• If a setting is set in one instance of the config object, it will be reflected in all other instances of the config object retrieved with the same call to get_config within the same process.
• This may not follow the Windows- or MacOS-specific conventions for the current year. The goal is to make something that works regardless. However, if the behavior of os.expanduser or os.getcwd changes, this may break in the future.

More Resources

Check out the Pycelium discord server. If you experience a problem, please discuss it on the Discord server. All suggestions for improvement are also welcome, and the best place for that is also Discord. If you do not use Discord, open an issue or discussion thread on Github.

Testing

To test, clone the repo and then execute the test files.

On Windows:

python tests\test_base.py
python tests\test_windows.py

On civilized OSes:

find tests/ -name test_*.py -print -exec python {} \;

Testing suites are platform-specific, but the tests that should not run on a given platform will be skipped if their files are run.

There are a total of 28 tests: 18 test of the base class methods; 5 tests for POSIX systems; and 5 tests for Windows.

License

Copyright (c) 2026 Jonathan Voss (k98kurz)

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.