overscore

Library for double underscore access notation

Overscore provides a way to retrieve (and store) multi-dimensional data using a single string with double underscores.

Inspired by Django, the access string can be used as a routine argument or a URL parameter, allowing for complex access within simple contexts:

import overscore

data = {
    "things": {
        "a": {
            "b": [
                {
                    "1": "yep"
                }
            ]
        }
    }
}

overscore.get(data, "things__a__b__0____1")
# "yep"

All keys/indexes are separated by double underscores. Extra underscores dictate how to parse that place in the path.

Underscores and Behavior

Underscores	Following	Meaning	Example	Equivalent
2	letters and numbers	key	a__b	[“a”][“b”]
2	numbers	index	a__1	[“a”][1]
3	numbers	negative index	a___2	[“a”][-2]
4	numbers	numerical key	a____3	[“a”][“3”]
5	numbers	neagtive numerical key	a_____4	[“a”][“-4”]

overscore.NUMBER

regex matching a number

overscore.WORD

regex matching a word

overscore.has(data, path) → bool

Indicates whether path exists in data

Parameters:

• data (dict or list or str) – The multidimensional data

• path (list or str) – The double underscored path to the intended value

Return type:

bool

Usage

You can check via a string:

import overscore

data = {
    "things": {
        "a": {
            "b": [
                {
                    "1": "yep"
                }
            ]
        }
    }
}

overscore.has(data, "things__a__b__0____1")
# True

Or using via a list:

overscore.has(data, ["things", "a", "b", 0, "1"])
# True

overscore.get(data, path)

Retrieves the value in multidimensional data at the double underscored path

Parameters:

• data (dict or list or str) – The multidimensional data

• path (list or str) – The double underscored path to the intended value

Usage

You can retrieve via a string:

import overscore

data = {
    "things": {
        "a": {
            "b": [
                {
                    "1": "yep"
                }
            ]
        }
    }
}

overscore.get(data, "things__a__b__0____1")
# "yep"

Or using via a list:

overscore.get(data, ["things", "a", "b", 0, "1"])
# "yep"

overscore.set(data, path, value)

Stores a value in multidimensional data at the double underscored path, creating necessary structures along the way

Parameters:

• data (dict or list or str) – The multidimensional data

• path (list or str) – The double underscored path to the intended value

• value – The value to store

Usage

You can store via a string:

import overscore

data = {}

overscore.set(data, "things__a__b___2____1", "yep")
data
# {
#     "things": {
#         "a": {
#             "b": [
#                 {
#                     "1": "yep"
#                 },
#                 None
#             ]
#         }
#     }
# }

Or using via a list:

overscore.set(data, ["things", "a", "b", -2, "1"], "sure")
data
# {
#     "things": {
#         "a": {
#             "b": [
#                 {
#                     "1": "sure"
#                 },
#                 None
#             ]
#         }
#     }
# }

overscore.parse(text: str) → list

Parses text to a list of keys/indexes

Parameters:

text (str) – path to parse

Return type:

list

Usage

import overscore

overscore.parse("a-b__0___1____2_____3")
# [
#     "a-b",
#     0,
#     -1,
#     "2",
#     "-3"
# ]

overscore.compile(path: list) → str

Compiles a list of keys/indexes to text

Parameters:

path (list) – The path to compile

Return type:

str

Usage

import overscore

overscore.compile(["a-b", 0, -1, "2", "-3"])
# "a-b__0___1____2_____3"

exception overscore.OverscoreError

Used for any overscore issues encountered.