Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Yet another application settings helper.

Project description

Yet another application settings helper.


It’s a common practice to put a settings file in a distribution package with some predefined stuff which can be overridden later in global project’s settings. But there is also a good reason to separate all your settings within your apps just like you do so with common python code: models, views, etc. That’s not a big thing if your project doesn’t come with dozen apps, but if it does, flushing out non-project stuff is a good way to not mess things around and keep them way simple.


Lets say you have an email service application in your project dir and it stores some configuration in


It’s a big temptation to write short USERNAME, but you have to use prefixes to prevent conflicts with other application settings and tell collaborators this is for the email app. And then:

# emails/
from django.conf import settings.

service = Service(username=settings.MYEMAILSERVICE_USERNAME,

Prefixes are everywhere. You always have to say MYEMAILSERVICE_ in every single place you need to access the settings. How about this one:

# Package settings in emails/
from pkgconf import Conf

class MyEmailService(Conf):
    USERNAME = 'username'
    PASSWORD = 'password'

    def DEBUG(self):
        return self.USERNAME.startswith('test_')

There is nothing more to say:

# emails/
# Note: your MyEmailService class becomes a module,
# you import it directly
from . import conf

service = Service(username=conf.USERNAME, password=conf.PASSWORD, ...)

django-pkgconf wraps your application settings and provides a handy shortcut.

But what about test or dev settings? Just define them like you always do (configuration class name becomes a prefix).

Old style:


Cool style (django-configurations way):

class Prod(Configuration):
    # No email service settings at all

class Test(Prod):
    MYEMAILSERVICE_USERNAME = 'test_username'

It looks for the required setting in django’s configuration file first and returns original value if it’s not overridden:

# emails/
from . import conf

conf.USERNAME  # 'test_username'
conf.PASSWORD  # 'password' - returns original value
conf.DEBUG  # True

Since 0.3.0 mixins are supported:

from pkgconf import Conf

class FacebookMixin:
    FACEBOOK_APP_ID = 'foo'

class TwitterMixin:
    TWITTER_APP_ID = 'foo'
    TWITTER_SECRET = 'bar'

class InstagramMixin:
    INSTAGRAM_APP_ID = 'foo'

class SocialAppConf(FacebookMixin, TwitterMixin, InstagramMixin, Conf):
    DEBUG = True


Install the package:

pip install -U django-pkgconf

Read the quickstart.


Build Status Codecov

Tested on py 3.5, 3.6, 3.7, 3.8 with django 1.11, 2.2, 3.0.

Powered siblings

There are more advanced apps with (probably) some extra (better?) options: django-appsettings, django-appconf, etc. The reason I’ve published this one is those apps are too big and tricky to do this little work, so you might prefer them instead.


  • Due to the code simplicity, property descriptor is used to get data from the settings. That means you can not set (or change) configuration values in action. I don’t know why you would do that, but I have to warn you.
  • Since your app’s settings are defined in separate file, they are not accessible via django.conf.settings (until you override them in your project settings). This application doesn’t create backward compatibility links. You should always use package configuration module.



  • Python 3 only


  • Added mixins support.

v0.2.1 - 0.2.2

  • Added import * support.
  • __prefix__ is generated automatically if not presented in class. That may help to build graceful exceptions like 'foo_value' was not found in MYAPP_FOO_SETTING.


  • Added __prefix__ attribute to support prefix-names with underscores.
  • Added instance method and property support.
  • Backward incompatible change: functions must have self as the first argument now.


  • First public release

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-pkgconf, version 0.4.0
Filename, size File type Python version Upload date Hashes
Filename, size django-pkgconf-0.4.0.tar.gz (6.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page