Skip to main content
Version: Next

Getting started

Installation

To install PREFS you need to have pip installed (if you don't have it installed see Pypi installation):

pip install prefs
tip
If you want to install some version and not the latest use pip install prefs=versionNumber. Or if you already have PREFS and you want to upgrade it use pip install prefs --upgrade (and look at the latest version of the documentation).

Once you have installed PREFS correctly create a new Python file and import prefs:

import prefs

Creating

To create a prefs file you will need to instance the Prefs class with the first argument as the default preferences.

info

The default preferences are the ones used the first time the program runs or whenever the file gets deleted.

import prefs

default_prefs = {
    "lang": "en", 
    "theme": "dark", 
    "scheme": {
        "background": "#AB2E6A", 
        "font-color": "#129396", 
        "font": "UbuntuMono"
    }
}

my_prefs = prefs.Prefs(default_prefs)

The above code will create a file that looks like:

prefs.prefs
#PREFS
lang='en'
theme='dark'
scheme=>
    background='#AB2E6A'
    font-color='#129396'
    font='UbuntuMono'

You can change the file's path with the path parameter.

info

If any directory in the path doesn't exist, it will get created.

Reading

To access to the content of the prefs file you can use the content property, but that is useless since the Prefs class acts like a dictionary. So, to access a key you can do it so

my_prefs["lang"]

And if you try and print it, you will get:

print(my_prefs)
>>> {'lang': 'en','theme': 'dark', 'scheme': {'background': '#AB2E6A', 'font-color': '#129396', 'font': 'UbuntuMono'}}

It is exactly the same as printing the content attribute:

print(my_prefs.content)
>>> {'lang': 'en','theme': 'dark', 'scheme': {'background': '#AB2E6A', 'font-color': '#129396', 'font': 'UbuntuMono'}}

At this point you should be wondering «How to access to the "background" value?», well, it is quite easy:

my_prefs["scheme/background"] # It is called key path

Writing

To change the value of a key may want to use the write() method, but again, Prefs offers a dictionary-like interface, so:

print(my_prefs["lang"])
>>> en

my_prefs["lang"] = "es"

print(my_prefs["lang"])
>>> es

And to change the value of background, use it's key path.

print(my_prefs["scheme/background"])
>>> #AB2E6A

my_prefs["scheme/background"] = "#56B8D1"

print(my_prefs["scheme/background"])
>>> #56B8D1

Any key that doesn't exist in the key path, will get created.
So we can do this:

my_prefs["scheme/font/family"] = "UbuntuMono"
my_prefs["scheme/font/color"] = "#129396"
my_prefs["scheme/font/size"] = 15
info

Nested assigment doesn't work.

my_prefs["scheme"]["font"]["family"] = "UbuntuMono" # Is not valid and won't work

You need to use key path, as the above example.

The prefs file will look like:

#PREFS
lang='en'
theme='dark'
scheme=>
    background='#56B8D1'
    font-color='#129396'
    font=>
        size=15
        family='UbuntuMono'
        color='#129396'

But there is problem, we don't need font-color anymore, we need to remove it, how?

Removing

To remove keys from the prefs file you can use the pop method (like a dictionary).

my_prefs.pop("scheme/font-color") # Key path is allowed

Which will end up in:

#PREFS
lang='en'
theme='dark'
scheme=>
    background='#56B8D1'
    font=>
        size=15
        family='UbuntuMono'
        color='#129396'

More

There are more useful methods, check them at the API reference:

And some useful functions that you can see at Functions.

note

If you are building an application, check PREFS resoureces.