granular-configuration-language 2.0.0

This configuration utility library allows your code use YAML as a configuration language for internal and external parties, allowing configuration to be crafted from multiple sources and merged just before use, with added YAML Tags that run lazily for added functionality.

granular-configuration-language

⚠️ This library is meant for trusted configuration files. ⚠️

Get started or read more at the documentation site.

Why does this exist?

This library exists to allow your code use YAML as a configuration language for internal and external parties, allowing configuration to be crafted from multiple sources and merged just before use, with added YAML Tags that run lazily for added functionality, and plugin support for creating custom YAML Tags.

Some use cases:

• You are writing a library to help connect to some databases. You want users to easily changes settings and defined databases by name.
  • Conceptual Example:
    • Library Code:

      CONFIG = LazyLoadConfiguration(
          Path(__file___).parent / "config.yaml",
          "./database-util-config.yaml",
          "~/configs/database-util-config.yaml",
          base_path="database-util",
          env_location_var_name="ORG_COMMON_CONFIG_LOCATIONS",
      )
      

    • Library configuration:

      database-util:
        common_settings:
          use_decimal: true
          encryption_type: secure
        databases: {} # Empty mapping, for users define
      

    • User application configuration:

      database-util:
        common_settings:
          use_decimal: false
        databases:
          datebase1:
            location: http://somewhere
            user: !Mask ${DB_USERNAME}
            password: !Mask ${DB_PASSWORD}
      

• You are deploying an application that has multiple deployment types with specific settings.
  • Conceptual Example:
    • Library Code:

      CONFIG = LazyLoadConfiguration(
          Path(__file___).parent / "config.yaml",
          "./database-util-config.yaml",
          base_path="app",
      )
      

    • Base configuration:

      app:
        log_as: really cool app name
        log_to: nowhere
      

    • AWS Lambda deploy:

      app:
        log_to: std_out
      

    • Server deploy:

      app:
        log_to: !Sub file://var/log/${$.app.log_as}.log
      

• You are writing a pytest plugin that create test data using named fixtures configured by the user.
  • Conceptual Examples:
    • Library Code:

      CONFIG = LazyLoadConfiguration(
          Path(__file___).parent / "fixture_config.yaml",
          *Path().rglob("fixture_config.yaml"),
          base_path="fixture-gen",
      ).config
      #
      for name, spec in CONFIG.fixtures:
          generate_fixture(name, spec)
      

    • Library configuration:

      fixture-gen:
        fixtures: {} # Empty mapping, for users define
      

    • User application configuration:

      fixture-gen:
        fixtures:
          fixture1:
            api: does something
      

Why the long name?

• It's "granular" because you can specify settings across multiple files at a fine granularity for overriding values.
• It is meant for trusted "configuration" files.
• Including "language" make it clear that this is not the source of configuration.
  • A valid piece of feedback was that it sounded like it was the source for configuration, not the processing of generic configuration files.
  • "Format" sounded weirder than "language".