Gin-Config

0.5.0 · active · verified Wed Apr 15

Gin provides a lightweight configuration framework for Python, based on dependency injection. Functions or classes can be decorated with @gin.configurable, allowing default parameter values to be supplied from a config file (or passed via the command line) using a simple but powerful syntax. This removes the need to define and maintain configuration objects or write boilerplate parameter plumbing and factory code, while often dramatically expanding a project's flexibility and configurability. It is particularly well suited for machine learning experiments. It is currently at version 0.5.0 and is actively maintained by Google.

Warnings

gotcha Confusion with 'gin-gonic/gin' (Go framework). There is a popular Go web framework also named 'Gin'. Ensure you are installing and referencing `gin-config` (for Python) and not the Go project.
Fix: Always use `pip install gin-config` for the Python library and refer to the official GitHub repository `google/gin-config` for documentation. When searching, be specific (e.g., 'gin-config python').
gotcha Distinction between `@gin.configurable` and `@gin.register`. Functions decorated with `@gin.configurable` will have their parameters overridden by Gin configurations even when called directly from other Python code. Functions with `@gin.register` will *not* have their parameters overridden when called directly; configurations only apply when they are referenced using the `@some_name` syntax within config files or other Gin contexts.
Fix: Choose the appropriate decorator based on whether you want direct calls to respect Gin's configuration or only indirect/referenced calls.
gotcha Handling required parameters with `gin.REQUIRED`. While `gin.REQUIRED` can be used as a default value in a function signature, it is generally more flexible and often preferred to provide `gin.REQUIRED` at the call site if the function might be called multiple times with different requirements.
Fix: Prefer `my_function(param=gin.REQUIRED)` when defining configurable functions if a parameter must always be supplied by Gin or the caller. Consider passing `gin.REQUIRED` at the call site for greater flexibility in some scenarios.
gotcha Arithmetic expressions are not supported in Gin config files. While the configuration syntax is Python-like and supports literals, comments, and line continuation, it does not evaluate arithmetic expressions.
Fix: Pre-calculate any necessary arithmetic values in your Python code before parsing or provide the final numeric literals directly in the `.gin` configuration file.
gotcha Pylint warnings for unused imports with configurable items. When using `@gin.configurable` or `@gin.register`, you must import all functions/classes that might be configured, even if only one is selected at runtime via the config. This can lead to `pylint` flagging 'unused imports'.
Fix: Suppress the `unused-import` pylint warning for modules containing multiple configurable items, or structure your code to minimize the number of configurable items within a single module.

Install

pip install gin-config Install latest version

Imports

gin
```
import gin
```
configurable
```
@gin.configurable
```
The decorator is usually accessed via the top-level 'gin' import.
register
```
@gin.register
```
The decorator is usually accessed via the top-level 'gin' import.
parse_config_file
```
gin.parse_config_file('config.gin')
```

parse_config_files_and_bindings

gin.parse_config_files_and_bindings(gin_files, gin_params)

query_parameter

gin.query_parameter('my_function.param_name')

REQUIRED
```
def my_function(param=gin.REQUIRED):
```

operative_config_str

config_string = gin.operative_config_str()

Quickstart

To get started with Gin-Config, you define functions or classes that you want to make configurable by decorating them with `@gin.configurable`. You then create a `.gin` configuration file where you specify parameter bindings using a `function_name.parameter_name = value` syntax. Finally, you parse this configuration file in your Python application using `gin.parse_config_file()`, and Gin-Config automatically injects the configured values when the decorated functions or classes are called.

import gin

# 1. Define a configurable function or class
@gin.configurable
def greet(name='World', greeting='Hello'):
    return f"{greeting}, {name}!"

# 2. Create a config file (e.g., config.gin)
# Save this content to a file named 'config.gin':
# greet.name = 'Gin-Config User'
# greet.greeting = 'Hi there'

# 3. In your Python code, parse the config file
# For demonstration, we'll use gin.parse_config_string
# In a real application, you'd use gin.parse_config_file('config.gin')
gin_config_content = """
greet.name = 'Gin-Config User'
greet.greeting = 'Hi there'
"""
gin.parse_config_string(gin_config_content)

# 4. Call the configurable function
# Gin will automatically inject parameters from the config
result = greet()
print(result)

# You can still override configured values by passing arguments directly
result_override = greet(name='Developer')
print(result_override)

# Clear configurations (useful for testing or multiple configurations)
gin.clear_config()

# Demonstrate gin.REQUIRED
@gin.configurable
def show_required(value=gin.REQUIRED):
    return f"Required value: {value}"

# Try to call without configuring or providing 'value'
try:
    show_required()
except ValueError as e:
    print(f"Expected error for missing required parameter: {e}")

# Configure and call
gin.parse_config_string("show_required.value = 42")
print(show_required())

view raw JSON →