Merge pull request #395 from aclist/chore/contributing-docs

docs: add contributing docs

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Introduction
+
+Thank you for your interest in DZGUI!
+
+This guide goes over development conventions and best practices for contributors.
+If you are a developer, you can skip to the end.
+
+# Requesting help
+
+If you encounter a problem with DZGUI, you can submit tickets on the GitHub
+(issue tracker)[https://github.com/aclist/dztui/issues] under the
+`troubleshooting` tag.
+
+# How can I help the project?
+
+There are several ways to help this project.
+1. Report bugs that you find
+2. Request features that you would like
+3. Contribute features and fixes to the codebase
+4. Contribute documentation to the project
+
+Before making any contribution, please read the `CODE_OF_CONDUCT.md` and act
+accordingly.
+
+## Submitting a ticket
+
+Navigate to the GitHub (issue tracker)[https://github.com/aclist/dztui/issues].
+From there, follow the onscreen prompts. You will be asked questions such as:
+
+- What version are you using?
+- What distribution are you using?
+- What is the issue that you found?
+- How can we reproduce the issue?
+
+You can also attach screenshots, logs, or other data that can help us.
+
+## Requesting a feature
+
+You can also request features via the same issue tracker. It is good practice to
+first search for your idea to see if a similar one has already been posted.
+If not, open a ticket where you describe your feature and its possible benefits.
+
+Please note that this is a community project, so it takes time for us to develop
+features. Putting in a feature request does not mean that it will be implemented,
+but we will do our best to support as many cool ideas as possible.
+
+## Contributing code or documentation
+
+If you would like to assist with an issue on the issue tracker or
+contribute a new change, please follow the guidelines below.
+
+Fork this repository and check out the code up to the `dzgui7` (development) branch.
+
+The following naming conventions apply for PRs:
+- fix/<your-fix> - patch/hotfix branches
+- feat/<your-feature> - feature branches
+- doc/<your-doc-branch> - documentation branches
+- infra/<your-infra-branch> - infrastructure branches
+
+Implement your changes and test them locally. If they work, you may
+open a merge request, and then we review your changes. If everything is OK, it
+will be merged to `dzgui7`. After sufficient changes are consolidated into a new release,
+this branch will be tagged to a certain point in time and a binary release published.
+
+It is recommended to follow
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), as this
+integrates well with tooling and helps the project review your code.
+
+Please see DEVELOPERS.md for further details.

README.md

@@ -24,13 +24,8 @@ Please refer to the documentation for installation and setup instructions:
 
 Geolocation records from [DB-IP](https://db-ip.com) under [CC 4.0 license](https://creativecommons.org/licenses/by/4.0/)
 
-This tool uses [python-a2s](https://github.com/Yepoleb/python-a2s) and [dayzquery](https://github.com/Yepoleb/dayzquery) as submodules; licenses for these submodules can be found in the LICENSES file
-of the project root.
-
-Both the geolocation records and submodules listed above are not shipped with the source code, but are retrieved and assembled at runtime.
-
-Finally, executable versions of DZGUI shipped as release binaries are thin wrappers around the Python interpreter, and also retrieve and assemble the above dependencies at runtime on the end-user's
-machine, rather than using pre-compiled source code. Users wishing to review these dependencies can inspect the 'pyproject.toml' manifest in the project root.
+Executable versions of DZGUI published as release binaries ship with various runtime dependencies and the Python interpreter built in.
+Users wishing to review the licenses to these components can inspect the `LICENSE` file located in the release tarball.
 
 ## Disclaimer
 

docs/source/dzgui7.rst

@@ -26,7 +26,7 @@ You can install it via the following set of commands:
 .. code:: console
 
    sudo apt update
-   sudo apt install libgirepository-2.0
+   sudo apt install libgirepository-2.0-0
 
 Next steps
 ---------------

dzgui/app_init.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import shutil
 from typing import TYPE_CHECKING
 
 
@@ -20,6 +21,7 @@ from dzgui.strings import boot
 # from dzgui.util.map_count import get_map_count
 from dzgui.util.deck import is_steam_deck, is_game_mode
 from dzgui.util.localize import set_locale
+from dzgui.util.redact import RedactionFilter, REDACTION_PATTERNS
 from dzgui.util.strings import init
 
 from dzgui.views.base import App
@@ -39,17 +41,63 @@ def make_parents(path: "Path") -> None:
 
 
 def setup_logger(log_path: "Path") -> None:
+    # TODO: put in consts?
     _format = (
         "%(asctime)s␞%(levelname)s␞%(filename)s::%(funcName)s::%(lineno)s␞%(message)s"
     )
+
     fh = logging.FileHandler(log_path)
     formatter = logging.Formatter(_format)
     fh.setFormatter(formatter)
     fh.setLevel(logging.DEBUG)
+
+    _filter = RedactionFilter(patterns=REDACTION_PATTERNS)
+    fh.addFilter(_filter)
+
     logger.setLevel(logging.DEBUG)
     logger.addHandler(fh)
 
 
+def copy_bare_configs(config: "Path", resolution: "Path") -> tuple[bool, bool]:
+    # NOTE: temporary workaround for #375
+    conf = "config.json"
+    state = [
+        "dzg.history",
+        "dzg.versions",
+        "dzg.res.json",
+        "dzg.filters.json",
+        "dzg.columns.json",
+        "dzg.notes.json",
+        "ips.csv",
+        ".month",
+    ]
+    config_changed = False
+    state_changed = False
+    if config.parent.exists() is False:
+        new_file = config
+        old_file = config.parent.parent / conf
+        if old_file.is_file():
+            try:
+                make_parents(new_file)
+                shutil.copy(old_file, new_file)
+                config_changed = True
+            except Exception as e:
+                logger.critical(e)
+    if resolution.parent.exists() is False:
+        state_path = resolution.parent
+        for state_file in state:
+            old_file = state_path.parent / state_file
+            if old_file.is_file():
+                try:
+                    new_file = state_path / state_file
+                    make_parents(new_file)
+                    shutil.copy(old_file, new_file)
+                    state_changed = True
+                except Exception as e:
+                    logger.critical(e)
+    return (config_changed, state_changed)
+
+
 def load_gui(version: str, is_debug: bool) -> None:
     lock = lock_acquire()  # noqa
 
@@ -58,6 +106,8 @@ def load_gui(version: str, is_debug: bool) -> None:
     xdg_paths = get_xdg_paths()
     XDG = parse_filepaths(xdg_paths)
 
+    copy_bare_configs(XDG.config, XDG.resolution)
+
     if XDG.resolution.parent.is_dir() is False:
         make_parents(XDG.resolution)
 

dzgui/config/xdg.py

@@ -29,9 +29,9 @@ def is_writeable(path_str: str) -> bool:
     if not path.exists():
         try:
             path.mkdir(parents=True)
+            path.unlink()
         except OSError:
             return False
-        path.unlink()
         return True
 
     try:
@@ -55,11 +55,12 @@ def get_xdg_paths() -> dict:
 
     resolved_paths = {}
     for path in xdg_paths:
-        rp = os.environ.get(path)
-        if rp is not None and is_writeable(rp):
-            resolved_paths[path] = Path(rp)
+        real_path = os.environ.get(path)
+        if real_path is not None and is_writeable(real_path):
+            new_path = Path(real_path)
         else:
-            resolved_paths[path] = xdg_paths[path] / APP_NAME_LOWER
+            new_path = xdg_paths[path]
+        resolved_paths[path] = new_path / APP_NAME_LOWER
     return resolved_paths
 
 

dzgui/init/libgi.py

@@ -1,11 +1,12 @@
 import platform
 import sys
 
-from pathlib import Path
+from ctypes.util import find_library
 from warnings import deprecated
 
 LIB = "libgirepository-2.0"
 
+
 @deprecated("currently unused")
 def is_debian() -> bool:
     """
@@ -39,9 +40,7 @@ def is_debian() -> bool:
 
 
 def has_libgi() -> bool:
-    parent_dir = Path("/usr/lib64")
-    exists = any(LIB in subdir.name for subdir in parent_dir.iterdir())
-    return exists
+    return bool(find_library("girepository-2.0"))
 
 
 def test_libgi_missing() -> None:

dzgui/model/model_factory.py

@@ -2,7 +2,6 @@ from dataclasses import dataclass
 from typing import Any, Sequence, TYPE_CHECKING
 
 from dzgui.const.enum import HELP_MENU_ROWS
-from dzgui.util.redact import redact_log
 from dzgui.util.strings import delimiter
 
 import gi
@@ -134,9 +133,7 @@ class ModelFactory:
         with open(path, "r") as f:
             lines = [line.split(delimiter) for line in f.read().splitlines()]
             for record in lines:
-                # NOTE: strips PII and API keys
-                clean = redact_log(record)
-                store.append(clean)
+                store.append(record)
         return store
 
     def new_model_from_class(self, cls: type) -> FastInsertListStore:

dzgui/util/diag.py

@@ -1,3 +1,4 @@
+import logging
 import os
 import platform
 
@@ -9,7 +10,9 @@ from dzgui.const.constants import APP_NAME
 from dzgui.const.enum import Preferences
 from dzgui.config.query import lookup
 from dzgui.init.prefix import get_version
-from dzgui.util.redact import redact
+from dzgui.util.redact import redact_home
+
+logger = logging.getLogger(APP_NAME)
 
 
 def get_cpu_model() -> str:
@@ -41,12 +44,16 @@ def write_diagnostic(config: Path, outfile: Path) -> None:
     # TODO: test availability on other distros
     date = datetime.now().isoformat()
 
-    distro = platform.freedesktop_os_release()["ID_LIKE"]
+    try:
+        distro = platform.freedesktop_os_release()["ID_LIKE"]
+    except Exception as e:
+        logger.warn(e)
+        distro = "Unknown"
+
     kernel = os.uname().release
     cpu = get_cpu_model()
     version = get_version()
 
-    branch = lookup(config, Preferences.BRANCH)
     debug = lookup(config, Preferences.DEBUG)
     install = lookup(config, Preferences.INSTALL)
     default = lookup(config, Preferences.DEFAULT)
@@ -54,8 +61,8 @@ def write_diagnostic(config: Path, outfile: Path) -> None:
     steam_path = Path(default)
     workshop_path = get_local_mod_path(steam_path)
 
-    steam_redacted = redact(default)
-    workshop_redacted = redact(str(workshop_path))
+    steam_redacted = redact_home(default)
+    workshop_redacted = redact_home(str(workshop_path))
 
     mods = get_local_mod_ids(steam_path)
     mods_pretty = print_mods(mods)
@@ -65,7 +72,7 @@ def write_diagnostic(config: Path, outfile: Path) -> None:
 
     # FIXME: extraneous newlines in lists of mods
     template = f"""\
-    {APP_NAME} version {version} ({branch})
+    {APP_NAME} version {version}
     Date: {date}
     ===============================
     Distribution: {distro}

dzgui/util/redact.py

@@ -1,20 +1,29 @@
+import logging
 import re
+from typing import Literal
 
-def redact(text: str) -> str:
-    r = r"(/home/)([^/])*"
-    cleaned = re.sub(r, r"/home/REDACTED", text)
+api_filter = r"(.*&key=)([^&]*)(.*)"
+home_filter = r"(/home/)([^\s'\/]*)(.*)"
+REDACTED = r"\1REDACTED\3"
+REDACTION_PATTERNS = [api_filter, home_filter]
+
+
+def redact_home(text: str) -> str:
+    pat = re.compile(home_filter)
+    cleaned = pat.sub(REDACTED, text)
     return cleaned
 
-def redact_log(record: list) -> list[str]:
-    """
-    requests library includes Steam API key in URL params
-    """
-    clean = []
-    for item in record:
-        if "&key=" in item:
-            pat = r"(.*&key=)(\S+)(.*)"
-            scrubbed = re.sub(pat, r"\1REDACTED\3", item)
-            clean.append(scrubbed)
-        else:
-            clean.append(item)
-    return clean
+
+class RedactionFilter(logging.Filter):
+    def __init__(self, patterns: list[str] | None = None) -> None:
+        super().__init__()
+        self._patterns = [re.compile(pat) for pat in (patterns or [])]
+
+    def filter(self, record: logging.LogRecord) -> Literal[True]:
+        for pattern in self._patterns:
+            try:
+                record.msg = pattern.sub(REDACTED, record.msg)
+            except TypeError:
+                exception_text = f"{type(record.msg).__name__}: {record.msg}"
+                record.msg = pattern.sub(REDACTED, exception_text)
+        return True

dzgui/views/pages/options.py

@@ -288,6 +288,7 @@ class Options(Gtk.Box):
 
     def _on_api_change_failed(self, emitter: "Emitter") -> None:
         self.old_entry.set_text(self.old_text)
+        # TODO: use popover
         dialog = ExceptionDialog(self.controller, errors.api_validation_error)
         dialog.run()
 

pyproject.toml

@@ -4,7 +4,7 @@ description = "DayZ server browser and mod manager for Linux"
 authors = [
     {name = "aclist"}
 ]
-version = "7.0.0b14"
+version = "7.0.0b15"
 license = "GPL-3.0-or-later"
 license-files = ["LICENSE"]
 readme = "README.md"
@@ -110,6 +110,7 @@ markers = [
     "mods: tests mod metadata/link creation",
     "pefile: validate PE files",
     "post_install: requires a completed installation",
+    "redact: log redaction mechanisms",
     "slow: long-running tests",
     "webtest: checks remote endpoints"
 ]

tests/test_bare_conf_files.py

@@ -0,0 +1,85 @@
+import pytest
+import tempfile
+import os
+
+from dzgui.app_init import copy_bare_configs
+from dzgui.config.xdg import get_xdg_paths, parse_filepaths
+
+
+CONF_STRING = "DZGUI_CONF\n"
+STATE_STRING = "DZGUI_STATE\n"
+
+
+@pytest.fixture
+def state_files():
+    state = [
+        "dzg.history",
+        "dzg.versions",
+        "dzg.res.json",
+        "dzg.filters.json",
+        "dzg.columns.json",
+        "dzg.notes.json",
+        "ips.csv",
+        ".month",
+    ]
+    return state
+
+
+@pytest.fixture
+def xdg_paths(monkeypatch):
+    routes = {
+        "XDG_CONFIG_HOME": "",
+        "XDG_STATE_HOME": "",
+        "XDG_DATA_HOME": "",
+        "XDG_CACHE_HOME": "",
+    }
+    for route in routes:
+        tmp = tempfile.TemporaryDirectory(delete=False)
+        routes[route] = tmp.name
+    for k, v in routes.items():
+        monkeypatch.setenv(k, v)
+    env = get_xdg_paths()
+    return parse_filepaths(env)
+
+
+@pytest.mark.mods
+def test_config_file_import(xdg_paths, state_files):
+
+    # NOTE: write bare files in root
+    tmp_conf = xdg_paths.config.parent.parent
+    tmp_conf_file = tmp_conf / xdg_paths.config.name
+    tmp_conf_file.write_text(CONF_STRING)
+
+    tmp_state = xdg_paths.resolution.parent.parent
+    for file in state_files:
+        tmp_state.joinpath(file).write_text(STATE_STRING)
+    # NOTE: function should move files into "dzgui" subdirectory
+    config_changed, state_changed = copy_bare_configs(
+        xdg_paths.config, xdg_paths.resolution
+    )
+
+    assert xdg_paths.config.read_text() == CONF_STRING
+    for file in state_files:
+        expected = xdg_paths.resolution.parent.joinpath(file)
+        assert expected.read_text() == STATE_STRING
+
+    assert config_changed is True
+    assert state_changed is True
+
+
+@pytest.mark.mods
+def test_config_file_no_import(xdg_paths, state_files):
+    for subdir in xdg_paths.config.parent, xdg_paths.resolution.parent:
+        subdir.mkdir()
+
+    tmp_conf_file = xdg_paths.config
+    tmp_conf_file.write_text(CONF_STRING)
+
+    for file in state_files:
+        xdg_paths.resolution.parent.joinpath(file).write_text(STATE_STRING)
+
+    config_changed, state_changed = copy_bare_configs(
+        xdg_paths.config, xdg_paths.resolution
+    )
+    assert config_changed is False
+    assert state_changed is False

tests/test_config.py

@@ -95,8 +95,3 @@ def test_missing_values(unset_values):
     j = convert.rc2json(unset_values)
     j = json.loads(j)
     assert j.keys() == config_boilerplate.keys()
-
-
-
-
-# TODO: test that when a config file is created from scratch, it contains all values

tests/test_log_redaction.py

@@ -0,0 +1,54 @@
+import logging
+import pytest
+
+from dzgui.util.redact import RedactionFilter, REDACTION_PATTERNS
+
+
+class RecordsListHandler(logging.Handler):
+    def __init__(self) -> None:
+        super().__init__()
+        self.records_list = []
+
+    def emit(self, record: logging.LogRecord) -> None:
+        self.records_list.append(record)
+
+    def pop(self) -> None:
+        return self.records_list[-1].msg
+
+
+@pytest.mark.redact
+@pytest.mark.parametrize(
+    "log_error, expect",
+    [
+        ("/home/SENSITIVE_USERNAME/subdir", "/home/REDACTED/subdir"),
+        (
+            "https://url.com/?api&key=SENSITIVE_KEY&results=10",
+            "https://url.com/?api&key=REDACTED&results=10",
+        ),
+        (
+            "https://url.com/?api&key=SENSITIVE_KEY",
+            "https://url.com/?api&key=REDACTED",
+        ),
+        (
+            "Error in directory: '/home/SENSITIVE_USERNAME/'",
+            "Error in directory: '/home/REDACTED/'",
+        ),
+        (
+            "Error in directory: '/home/SENSITIVE_USERNAME'",
+            "Error in directory: '/home/REDACTED'",
+        ),
+    ],
+)
+def test_log_redaction(log_error: str, expect: str) -> None:
+    logger = logging.getLogger("TEST")
+
+    handler = RecordsListHandler()
+    logger.addHandler(handler)
+    logger.setLevel(logging.DEBUG)
+
+    _filter = RedactionFilter(patterns=REDACTION_PATTERNS)
+    logger.addFilter(_filter)
+
+    logger.critical(log_error)
+    redacted = handler.pop()
+    assert expect == redacted

tests/test_remote_api.py

@@ -20,7 +20,6 @@ def test_steam(config):
     key = config["steam_api"]
     assert probe.test_steam_api(key)
 
-
 def test_bm(config):
     key = config["bm_api"]
     assert probe.test_bm_api(key)