Documentation of myminions’s¶
- by David Scheliga
My minions is a loose collection of frequently used methods doing basic bidding’s.
Installation¶
Either install the current release from pip …
pip install myminions
… or the latest *dev*elopment state of the gitlab repository.
$ pip install git+https://gitlab.com/david.scheliga/myminions.git@dev --upgrade
Module content¶
Helper for testing¶
-
myminions.
copy_tree
(source_path: Union[str, pathlib.Path, os.PathLike], destination_path: Union[str, pathlib.Path, os.PathLike])¶ Copies the content of the source tree to the destination.
Parameters: - source_path – The source path which content is to be copied.
- destination_path – The destination in which to copy.
Examples
>>> from doctestprinter import doctest_iter_print >>> from tempfile import TemporaryDirectory >>> with TemporaryDirectory() as temp_dir: ... target_path = Path(temp_dir).joinpath("test") ... copy_tree("./tests/resources", target_path) ... success_of_copy = file_trees_have_equal_paths( ... expected_tree_path="./tests/resources", ... target_tree_path=target_path ... ) ... relative_test_files = list_tree_relatively(target_path) >>> print("Copying trees was successful:", success_of_copy) Copying trees was successful: True >>> doctest_iter_print(sorted(relative_test_files, key=lambda x: str(x))) resources_index.md sample-1 sample-1/.hidden sample-1/file-1.txt sample-1/file-2.csv
-
myminions.
file_trees_have_equal_paths
(expected_tree_path: Union[str, pathlib.Path, os.PathLike], target_tree_path: Union[str, pathlib.Path, os.PathLike]) → bool¶ Checks if two file trees are structured equally on basis of their filepaths. The content of these files is not checked within this function.
Parameters: - expected_tree_path – The tree path which paths are expected.
- target_tree_path – The tree path to check against the expected tree path.
Returns: bool
Examples
>>> file_trees_have_equal_paths( ... expected_tree_path="./tests/resources", ... target_tree_path="./tests/resources" ... ) True
>>> file_trees_have_equal_paths( ... expected_tree_path="./tests/resources", ... target_tree_path="./tests" ... ) False
-
myminions.
list_tree_relatively
(root_path: Union[str, pathlib.Path, os.PathLike]) → List[pathlib.Path]¶ List all paths within the root_path relative to it.
Parameters: root_path – The root path which paths shall be listed. Returns: List[Path] Examples
>>> from doctestprinter import doctest_iter_print >>> samples = list_tree_relatively(root_path="./tests/resources") >>> doctest_iter_print(sorted(samples, key=lambda x:str(x))) resources_index.md sample-1 sample-1/.hidden sample-1/file-1.txt sample-1/file-2.csv
-
myminions.
remove_path_or_tree
(root_path_to_remove: Union[str, pathlib.Path, os.PathLike])¶ Removes the path, either if it is just a path or a whole path tree.
Examples
>>> from tempfile import TemporaryDirectory >>> with TemporaryDirectory() as tempdir: ... target_path = Path(tempdir).joinpath("test") ... copy_tree("./tests/resources", target_path) ... copy_was_successful = target_path.joinpath("sample-1/.hidden").exists() ... remove_path_or_tree(target_path) ... removing_the_path_was_successful = not target_path.exists() >>> print("Copying the tree was successful:", copy_was_successful) Copying the tree was successful: True >>> print("Removing the tree was successful:", removing_the_path_was_successful) Removing the tree was successful: True
Raises: TypeError
– If somethink else is providen than the expected a str, bytes or os.PathLike object.Parameters: root_path_to_remove (APath) – Root path to remove. Returns: bool
-
myminions.testing.
assert_existing_rel_paths_within_tree
(expected_rel_paths: List[Union[str, pathlib.Path, os.PathLike]], target_path: Union[str, pathlib.Path, os.PathLike])¶ Asserts whether the expected file paths are within the target path. This method is meant for testing purposes.
Notes
After moving files or copying this function asserts the success of the operation.
Parameters: - expected_rel_paths – Expected sub paths relative to the target path.
- target_path – The target path which should contain the expected sub paths.
Examples
>>> import glob >>> from doctestprinter import doctest_iter_print >>> test_tree = list(sorted(glob.glob("./tests/resources/**", recursive=True))) >>> doctest_iter_print(test_tree) ./tests/resources/ ./tests/resources/resources_index.md ./tests/resources/sample-1 ./tests/resources/sample-1/file-1.txt ./tests/resources/sample-1/file-2.csv
>>> expected_sample_paths = [ ... "sample-1", ... "resources_index.md", ... "sample-1/file-1.txt", ... "sample-1/.hidden" ... ] >>> assert_existing_rel_paths_within_tree( ... expected_rel_paths=expected_sample_paths, ... target_path="tests/resources" ... )
>>> assert_existing_rel_paths_within_tree( ... expected_rel_paths=["is_not_there"], ... target_path="tests/resources" ... ) Traceback (most recent call last): ... AssertionError: Path 'tests/resources' doesn't contain these subpath(s) ['is_not_there'].
Saving stuff on Linux and on Windows¶
On one occasion changing, editing a text file in between Linux and Windows broke
the parsing with json and yaml. Originated from the module dicthandling
try_deconding_potential_text_content()
is moved to myminions.
-
myminions.
try_decoding_potential_text_content
(byte_like_content, encoding_format_tryouts: List[str] = None) → str¶ Tries to decode the given byte-like content as a text using the given encoding format types.
Notes
The first choice is ‘utf-8’, but in case of different OS are involved, some json files might been created using a different encoding, leading to errors. Therefore this methods tries the encondings listed in myminions.ENCODING_FORMAT_TRYOUTS by default.
Examples
>>> from myminions import try_decoding_potential_text_content >>> sample = '{"a": "test", "json": "string with german literals äöüß"}' >>> sample_latin_1 = sample.encode(encoding="latin-1") >>> sample_latin_1 b'{"a": "test", "json": "string with german literals äöüß"}' >>> try_decoding_potential_text_content(sample_latin_1) '{"a": "test", "json": "string with german literals äöüß"}' >>> sample_windows = sample.encode(encoding="windows-1252") >>> sample_windows b'{"a": "test", "json": "string with german literals äöüß"}' >>> try_decoding_potential_text_content(sample_windows) '{"a": "test", "json": "string with german literals äöüß"}'
Parameters: - byte_like_content – The text as byte-like object, which should be decoded.
- encoding_format_tryouts – List[str]: Formats in which the text might be encoded.
Raises: UnicodeDecodeError
Returns: Hopefully a proper decoded text.
Return type: str
-
myminions.
load_yaml_file_content
(filepath: Union[str, pathlib.Path, os.PathLike], default: dict = None) → dict¶ Load the yaml file content returning the parsed result.
Parameters: - filepath (Path) – The file path of the yaml file, which should be loaded and parsed.
- default (dict) – The default dict, which will be returned if the filepath doesn’t exist or the files content is ‘None’.
Examples
>>> load_yaml_file_content("file/not/existing.yml", default={"doc": "test"}) {'doc': 'test'}
>>> from tempfile import TemporaryDirectory >>> with TemporaryDirectory() as tempdir: ... test_filepath = Path(tempdir).joinpath("test.yml") ... test_filepath.touch() ... empty_test_content = load_yaml_file_content( ... filepath=test_filepath, default={} ... ) ... print(empty_test_content) {}
Returns: dict
-
myminions.
update_yaml_file_content
(filepath: Union[str, pathlib.Path, os.PathLike], new_content: dict)¶ Updates the existing content of a yaml file with the new content. If the file does not exist a new file will be created.
Notes
Overlapping values of new_content will override existing entries. Used method for merging the existing file content with the new content is
myminions.overlap_dict_branches()
.Examples
>>> from tempfile import TemporaryDirectory >>> from pathlib import Path >>> with TemporaryDirectory() as tempdir: ... temporary_filepath = Path(tempdir, "test.yml") ... update_yaml_file_content( ... temporary_filepath, {"a": 1, "b": {"de": "ep"}} ... ) ... update_yaml_file_content( ... temporary_filepath, {"b": {"de": {"eper": 2}}} ... ) ... print(load_yaml_file_content(temporary_filepath)) {'a': 1, 'b': {'de': {'eper': 2}}}
Parameters: - filepath (APath) – The file path of the yaml file, which should be loaded and parsed.
- new_content (dict) – The new content, which will be updated into the existing content. It should be parsable by pyyaml.