Gifnoc

Gifnoc is a unified configuration system for Python modules.

The main objective of gifnoc is to unify configuration files, environment variables and command-line options, across multiple modules. For example, module A and module B can both define their own configuration models through gifnoc, map some environment variables to keys in that configuration, and then you may configure A and B in the same file.

Gifnoc also aims to validate configuration through a typed model based on dataclasses and implemented by the serieux package, a dependency of gifnoc.

Features

Typed configuration using dataclasses and serieux
Use a single configuration tree for multiple libraries
Multiple configuration files can be easily merged
Easily embed configuration files in each other

Example

main.py

from dataclasses import dataclass, field
import gifnoc

@dataclass
class User:
    name: str
    email: str
    admin: bool

@dataclass
class Server:
    # Server post
    port: int = 8080
    # Server hostname
    host: str = "localhost"
    # List of users
    users: list[User] = field(default_factory=list)

# Define a configuration key
server_config = gifnoc.define("server", Server)

if __name__ == "__main__":
    # Load configuration from the file in $APP_CONFIG, if it exists
    # set_sources overrides any previous configuration
    # Each source can be a dictionary, ${envfile:...}, a Path object
    gifnoc.set_sources("${envfile:APP_CONFIG}")

    # Overlay configuration from environment variables
    # add_overlay adds on top of existing configuration
    gifnoc.add_overlay({
        "server.port": "${env:APP_PORT}",
        "server.host": "${env:APP_HOST}",
    })

    # Overlay configuration with --config, add options with mapping
    # --port will automatically use the type and documentation of Server.port
    gifnoc.cli(mapping={"server.port": "--port"})

    # server_config dynamically updates as sources/overlays are changed
    print("Port:", server_config.port)
    print("Host:", server_config.host)

    # You can apply local changes with a context manager, e.g. for testing:
    with gifnoc.overlay({"server.port": 90909}):
        print("Port:", server_config.port)  # Port: 90909

config.yaml

server:
  port: 1234
  host: here
  users:
    - name: Olivier
      email: ob@here
      admin: true
    # You can write a file path instead of an object
    - mysterio.yaml

mysterio.yaml

name: Mysterio
email: me@myster.io
admin: false

Usage:

python main.py --config config.yaml
APP_CONFIG=config.yaml python main.py
APP_PORT=8903 python main.py --config config.yaml
python main.py --config config.yaml --port 8903

Metadata

Release files for gifnoc 0.6.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gifnoc 0.6.3
File	Size	Uploaded
gifnoc-0.6.3.tar.gz	45.1 kB	Nov 3, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for gifnoc 0.6.3
File	Interpreter	ABI	Platform	Reset
gifnoc-0.6.3-py3-none-any.whl 9.2 kB Nov 3, 2025	Python 3	none	any	Details

Total release size: 54.3 kB

Release files / gifnoc-0.6.3.tar.gz

Download URL	gifnoc-0.6.3.tar.gz
Size	45.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`7c795da2459772911b381929d7b2d366b2b6007e6a367652d8f68f26414e9c98`
BLAKE2b-256 checksum How to use checksums	`bc764e249bfc8f530b3fefecefa50871639f75d2bec156a7e2ac9971e9abec1f`
Upload date	Nov 3, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/breuleux/gifnoc
Publishing commit: github.com/breuleux/gifnoc/tree/023a32825173225aa4d250ec91d0c505f3cc3c85

Workflow

Publishing configuration: github.com/breuleux/gifnoc/blob/023a32825173225aa4d250ec91d0c505f3cc3c85/.github/workflows/publish.yml
Publishing logs: github.com/breuleux/gifnoc/actions/runs/19050496150/attempts/1

Artifact

Subject: gifnoc-0.6.3.tar.gz
SHA-256 checksum: 7c795da2459772911b381929d7b2d366b2b6007e6a367652d8f68f26414e9c98 Verifying attestations

Release files / gifnoc-0.6.3-py3-none-any.whl

Download URL	gifnoc-0.6.3-py3-none-any.whl
Size	9.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`05b71f27ec2a9f6515aeecf2faa6377f6e5cf86461f2aaff9340726135eef4ff`
BLAKE2b-256 checksum How to use checksums	`c895797b37187bdc0dbde7656318a98883a7f46a5925c736a827bf3f4916e44c`
Upload date	Nov 3, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/breuleux/gifnoc
Publishing commit: github.com/breuleux/gifnoc/tree/023a32825173225aa4d250ec91d0c505f3cc3c85

Workflow

Publishing configuration: github.com/breuleux/gifnoc/blob/023a32825173225aa4d250ec91d0c505f3cc3c85/.github/workflows/publish.yml
Publishing logs: github.com/breuleux/gifnoc/actions/runs/19050496150/attempts/1

Artifact

Subject: gifnoc-0.6.3-py3-none-any.whl
SHA-256 checksum: 05b71f27ec2a9f6515aeecf2faa6377f6e5cf86461f2aaff9340726135eef4ff Verifying attestations