aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorEugene Triguba <eugenetriguba@gmail.com>2020-07-20 22:49:58 -0500
committerEugene Triguba <eugenetriguba@gmail.com>2020-07-20 22:49:58 -0500
commit8c28da679092d9debf7140974fa7d28dfeda8e21 (patch)
tree936deca1542b7099c583b3a1e8df2f1e661e687d
parentUse tomlkit instead of toml & specify packages to include (diff)
downloadconfig-file-8c28da679092d9debf7140974fa7d28dfeda8e21.zip
Redo docstrings and api for abstract parser
-rw-r--r--config_file/parsers/abstract_parser.py122
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