aboutsummaryrefslogtreecommitdiffstats
path: root/config_file/parsers/abstract_parser.py
blob: 40983b2b9f739987410f18cfb533167a7015ea95 (plain) (blame)
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