Release v0.4.5. (Installation)


configclasses provides a simple yet powerful way to define and fetch configuration values for your application by extending python’s dataclasses (PEP-557) with additional functionality.

Configuration values are fetched on demand from various sources, validated, and stored in a single strongly typed configuration object.

A Basic Example

from configclasses import configclass

# Wrap your configuration class in the `configclass` decorator
class Configuration:
    HOST: str
    PORT: int

# Fields are populated when you construct a Configuration instance
config = Configuration()

# Access fields by name.
config.HOST == "localhost"

That’s it!

You now have an easy to use configuration class that fetches and validates all the configuration values your application requires. It defaults to searching environment variables to populate fields. In this case, it expects environment variables to be set for HOST and PORT.

A Slightly More Advanced Example

The configclass decorator also accepts user-specified sources of configuration data.

from configclasses import configclass, sources
from configclasses.sources import CommandLineSource, DotEnvSource, EnvironmentSource

# Create multiple sources of configuration information, and pass them to the
# `configclass` decorator.
@configclass(sources=[DotEnvSource(path=".env"), EnvironmentSource(), CommandLineSource()])
class Configuration:
    HOST: str = "localhost"  # Set a default value
    PORT: int

# Instantiating `Configuration` will always return the same
# singleton object. This way you can create a reference to
# it from any module you like and the configuration values
# will be consistent from instance to instance.
config = Configuration()

# Access fields by name.
config.HOST == "localhost"

The Configuration class will now search command line arguments, environment variables, and a .env file for HOST and PORT.

If a field name is found in multiple sources, sources are prioritized based on how they are passed to the configclass decorator. Sources are prioritized from left to right, giving the last source the highest priority.


  • Globally accessible configuration classes
  • Easily pull from many sources of configuration:
    • Environment variables
    • Command line arguments
    • Dotenv files
    • Json files
    • Toml files
    • Ini files
    • Consul Key/Value store
    • Planned sources: AWS Parameter Store, Etcd, Redis
  • Specify prioritization when multiple sources are used together.
  • Support for strongly typed configuration values out of the box:
    • primitive types such as int, float, and str are supported.
    • Enum types can be used to specify valid values
    • converter functions can turn stringly typed values complex types such as dicts or your own types.

Planned work

  • Deal with sources that only provide stringly typed values and values that provide other primitives
  • Some sources might be case-insensitive.
  • Async/Sync versions of sources
  • Research and design push updates (as opposed to polling updates)
  • Better error messages when config values are missing from all sources
  • Audit exception types raised.
  • Comprehensive docs
    • Includes docs on adding your own sources.

User’s Guide

Tutorials to guide you through the most common uses of the library as well as more advanced scenarios.

API Documentation

Here is where you’ll find comprehensive documentation for the public api.


Contributors are the best!


Licensor solely permits licensee to license under either of the following two options

Indices and tables