diff options
| author | Eugene Triguba <eugenetriguba@gmail.com> | 2020-07-20 22:49:58 -0500 |
|---|---|---|
| committer | Eugene Triguba <eugenetriguba@gmail.com> | 2020-07-20 22:49:58 -0500 |
| commit | 8c28da679092d9debf7140974fa7d28dfeda8e21 (patch) | |
| tree | 936deca1542b7099c583b3a1e8df2f1e661e687d | |
| parent | Use tomlkit instead of toml & specify packages to include (diff) | |
| download | config-file-8c28da679092d9debf7140974fa7d28dfeda8e21.zip | |
Redo docstrings and api for abstract parser
| -rw-r--r-- | config_file/parsers/abstract_parser.py | 122 |
1 files changed, 82 insertions, 40 deletions
diff --git a/config_file/parsers/abstract_parser.py b/config_file/parsers/abstract_parser.py index 8f1bee1..ed9430b 100644 --- a/config_file/parsers/abstract_parser.py +++ b/config_file/parsers/abstract_parser.py @@ -3,73 +3,115 @@ from typing import Any class AbstractParser(ABC): - """ - The abstract base parser for all other parsers to implement. + """Abstract Parser is the API contract for all parsers. + + 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. - All the keys are specified in a 'dot' syntax. So if you have - sections with subsections with a key that you're trying to get - the value of, you'd use 'section.subsection.key' as the key parameter. + Args: + file_contents: The stringified version of a file. + + Attributes: + file_contents: The stringified version of a file. """ @abstractmethod def __init__(self, file_contents: str) -> None: - """ - All parsers will take in the file as a string, parse - them internally to their own representation that they - can work with, and are able to stringify them back out - when we need to save (write) them. - - It is up to the caller of the parser to read in the file to - the parser and save the file when they are done using stringify(). - """ - self.content = file_contents - self.parsed_content = self.parse(self.content) + self.file_contents = file_contents @abstractmethod - def parse(self, file_contents: str) -> Any: - """ - Parse the file_contents into an internal representation - the given parser can work with. + 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, parse_types: bool = False, all: bool = False) -> Any: - """ - Retrieve the value of a key in its native type. - This means the string 'true' will be parsed back as the - boolean True. + def get(self, key: str) -> Any: + """Retrieve the value of a key from the working file. + + Args: + key: The key to retrieve. - If parse_types is set to False, all values will be returned - back as strings. + Returns: + Whatever value the given key happens to contain. + + Raises: + MissingKeyError: If the key to retrieve does not exist. """ raise NotImplementedError @abstractmethod - def set(self, key: str, value: Any) -> bool: - """Sets the value of a key.""" + 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, section_key: str) -> bool: - """Deletes a key/value pair or entire sections.""" + def delete(self, key: str) -> None: + """Deletes a key from the working file. + + Args: + key: The key we would like to remove. + + Raises: + MissingKeyError: If the key to remove does not exist. + """ raise NotImplementedError @abstractmethod def stringify(self) -> str: - """ - Using self.__contents, converts the parsed internal representation - of the file back into a string. + """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, section_key: str) -> bool: - """ - Check if a section, sub-section, or key exists in the file - using a section.key format. + def has(self, key: str) -> 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. - Some formats, like JSON, do not have sections and therefore, - it would only be checking if a certain key exists. + Returns: + True if the working file has the key. False otherwise. """ raise NotImplementedError |