1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
from abc import ABC, abstractmethod
from typing import Any
class AbstractParser(ABC):
"""Abstract Parser is the API contract for a parser for
use in the ConfigFile object.
Every parser in ConfigFile implements this parser, and
any user created parsers must implement this parser in
order for this package to be able to use it.
Every key is specified in a dot (.) syntax
e.g. retrieving.some.deeply.nested.value
If there is no dot in the key, it is assumed we are
performing an action on a top level key, which could
be an entire section.
Args:
file_contents: The stringified version of a file.
"""
@abstractmethod
def __init__(self, file_contents: str) -> None:
self.file_contents = file_contents
@property
@abstractmethod
def parsed_content(self) -> dict:
"""To be able to index into the ConfigFile object,
we have to expose the parsed dictionary object.
Raises:
KeyError: If the key we are trying to index into
does not exist.
Returns:
The internal contents parsed as a dictionary.
"""
raise NotImplementedError
@abstractmethod
def reset_internal_contents(self, file_contents: str) -> None:
"""Reset the state of this parser to a new file.
When restoring to the original file in ConfigFile,
we need a way to reset the internal contents to this
new file.
While this may be as simple as setting the file_contents
attribute value to the passed in file_contents argument,
it likely would not be. This is because the initial
passed in file contents would likely be parsed into some
special form for the parser to work with more easily.
Args:
file_contents: The file contents of the new file.
"""
raise NotImplementedError
@abstractmethod
def get(self, key: str) -> Any:
"""Retrieve the value of a key from the working file.
Args:
key: The key to retrieve.
Returns:
Whatever value the given key happens to contain.
Raises:
KeyError: If the key to retrieve does not exist.
"""
raise NotImplementedError
@abstractmethod
def set(self, key: str, value: Any) -> None:
"""Set the value of a key in the working file.
If the key does not exist, it should be created.
Args:
key: The key to set.
value: The value to set the key to.
"""
raise NotImplementedError
@abstractmethod
def delete(self, key: str) -> None:
"""Deletes a key from the working file.
Args:
key: The key we would like to remove.
Raises:
KeyError: If the key to remove does not exist.
"""
raise NotImplementedError
@abstractmethod
def __str__(self) -> str:
"""
Stringify the working file.
Since the ConfigFile does not write out to disk
after every operation, this method is what is
used as the output for saving the file again.
This parser should never write out to the disk.
Returns:
The file we are working with as a string.
"""
raise NotImplementedError
@abstractmethod
def has(self, key: str, wild: bool = False) -> bool:
"""Check whether the given key is in the parsed working file.
This should not behave like a wild card, as in check
if the key exists anywhere in the working file. Instead,
if a key is given without a dot, it should be assumed we
are checking the top level.
Args:
key: The key to search for.
wild: Optionally search for any occurrence of key in the file.
Returns:
True if the working file has the key. False otherwise.
"""
raise NotImplementedError
|