winipedia-utils 0.3.43__py3-none-any.whl → 0.4.18__py3-none-any.whl

winipedia_utils/testing/config.py

@@ -13,34 +13,65 @@ class PythonConfigFile(ConfigFile):
 
     CONTENT_KEY = "content"
 
-    def load(self) -> dict[str, str]:
+    @classmethod
+    def load(cls) -> dict[str, str]:
         """Load the config file."""
-        return {self.CONTENT_KEY: self.path.read_text()}
+        return {cls.CONTENT_KEY: cls.get_path().read_text()}
 
-    def dump(self, config: dict[str, Any]) -> None:
+    @classmethod
+    def dump(cls, config: dict[str, Any] | list[Any]) -> None:
         """Dump the config file."""
-        self.path.write_text(config[self.CONTENT_KEY])
-
-    def get_configs(self) -> dict[str, Any]:
+        if not isinstance(config, dict):
+            msg = f"Cannot dump {config} to python file."
+            raise TypeError(msg)
+        cls.get_path().write_text(config[cls.CONTENT_KEY])
+
+    @classmethod
+    def get_file_extension(cls) -> str:
+        """Get the file extension of the config file."""
+        return "py"
+
+    @classmethod
+    def get_configs(cls) -> dict[str, Any]:
         """Get the config."""
-        return {self.CONTENT_KEY: self.get_content()}
+        return {cls.CONTENT_KEY: cls.get_content_str()}
+
+    @classmethod
+    def get_file_content(cls) -> str:
+        """Get the file content."""
+        return cls.load()[cls.CONTENT_KEY]
 
+    @classmethod
     @abstractmethod
-    def get_content(self) -> str:
+    def get_content_str(cls) -> str:
         """Get the content."""
-        return self.load()[self.CONTENT_KEY]
 
+    @classmethod
+    def is_correct(cls) -> bool:
+        """Check if the config is correct.
 
-class ConftestConfigFile(PythonConfigFile):
-    """Config file for conftest.py."""
+        Python files are correct if they exist and contain the correct content.
+        """
+        return (
+            super().is_correct()
+            or cls.get_content_str().strip() in cls.load()[cls.CONTENT_KEY]
+        )
 
-    PATH = Path(f"{TESTS_PACKAGE_NAME}/conftest.py")
 
-    def get_path(self) -> Path:
+class PythonTestsConfigFile(PythonConfigFile):
+    """Base class for python config files in the tests directory."""
+
+    @classmethod
+    def get_parent_path(cls) -> Path:
         """Get the path to the config file."""
-        return self.PATH
+        return Path(TESTS_PACKAGE_NAME)
+
 
-    def get_content(self) -> str:
+class ConftestConfigFile(PythonTestsConfigFile):
+    """Config file for conftest.py."""
+
+    @classmethod
+    def get_content_str(cls) -> str:
         """Get the config content."""
         return '''"""Pytest configuration for tests.
 
@@ -55,21 +86,22 @@ pytest_plugins = ["winipedia_utils.testing.tests.conftest"]
 '''
 
 
-class ZeroTestConfigFile(PythonConfigFile):
-    """Config file for test_0.py."""
-
-    PATH = Path(f"{TESTS_PACKAGE_NAME}/test_0.py")
+class ZeroTestConfigFile(PythonTestsConfigFile):
+    """Config file for test_zero.py."""
 
-    def get_path(self) -> Path:
-        """Get the path to the config file."""
-        return self.PATH
+    @classmethod
+    def get_filename(cls) -> str:
+        """Get the filename of the config file."""
+        filename = super().get_filename()
+        return "_".join(reversed(filename.split("_")))
 
-    def get_content(self) -> str:
+    @classmethod
+    def get_content_str(cls) -> str:
         """Get the config."""
         return '''"""Contains an empty test."""
 
 
-def test_0() -> None:
+def test_zero() -> None:
     """Empty test.
 
     Exists so that when no tests are written yet the base fixtures are executed.
@@ -83,13 +115,35 @@ class ExperimentConfigFile(PythonConfigFile):
     Is at root level and in .gitignore for experimentation.
     """
 
-    PATH = Path("experiment.py")
-
-    def get_path(self) -> Path:
+    @classmethod
+    def get_parent_path(cls) -> Path:
         """Get the path to the config file."""
-        return self.PATH
+        return Path()
 
-    def get_content(self) -> str:
+    @classmethod
+    def get_content_str(cls) -> str:
         """Get the config."""
         return '''"""This file is for experimentation and is ignored by git."""
 '''
+
+
+class LocalSecretsConfigFile(PythonConfigFile):
+    """Config file for secrets.py.
+
+    Config file for secrets. Is added to .gitignore automatically.
+    Should be in .gitignore.
+    """
+
+    @classmethod
+    def get_parent_path(cls) -> Path:
+        """Get the path to the config file."""
+        return Path()
+
+    @classmethod
+    def get_content_str(cls) -> str:
+        """Get the config."""
+        return '''"""This file is for secrets you might use and is ignored by git.
+
+Can be used by tests or other developing code.
+"""
+'''

winipedia_utils/testing/tests/base/fixtures/fixture.py

@@ -4,3 +4,39 @@ This module provides custom fixtures for pytest that can be used to
 automate common testing tasks and provide consistent setup and teardown
 for tests.
 """
+
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+from winipedia_utils.text.config import ConfigFile
+
+
+@pytest.fixture
+def config_file_factory[T: ConfigFile](
+    tmp_path: Path,
+) -> Callable[[type[T]], type[T]]:
+    """Factory fixture for creating config file classes with tmp_path.
+
+    This factory wraps any ConfigFile subclass to use tmp_path for get_path().
+    Define tmp_path once here, then all test config classes inherit it.
+    """
+
+    def _make_test_config(
+        base_class: type[T],
+    ) -> type[T]:
+        """Create a test config class that uses tmp_path."""
+
+        class TestConfigFile(base_class):  # type: ignore [misc, valid-type]
+            """Test config file with tmp_path override."""
+
+            @classmethod
+            def get_path(cls) -> Path:
+                """Get the path to the config file in tmp_path."""
+                path = super().get_path()
+                return Path(tmp_path / path)
+
+        return TestConfigFile
+
+    return _make_test_config

winipedia_utils/testing/tests/base/fixtures/scopes/module.py

@@ -6,13 +6,16 @@ These fixtures are automatically applied to all test modules through pytest's au
 mechanism.
 """
 
+from typing import TYPE_CHECKING
+
 import pytest
 
-from winipedia_utils.modules.module import to_module_name
-from winipedia_utils.testing.config import ZeroTestConfigFile
 from winipedia_utils.testing.fixtures import autouse_module_fixture
 from winipedia_utils.testing.tests.base.utils.utils import assert_no_untested_objs
 
+if TYPE_CHECKING:
+    from types import ModuleType
+
 
 @autouse_module_fixture
 def assert_all_funcs_and_classes_tested(request: pytest.FixtureRequest) -> None:
@@ -29,7 +32,5 @@ def assert_all_funcs_and_classes_tested(request: pytest.FixtureRequest) -> None:
         AssertionError: If any function or class in the source module lacks a test
 
     """
-    module = request.module
-    if module.__name__ == to_module_name(ZeroTestConfigFile().get_path()):
-        return
+    module: ModuleType = request.module
     assert_no_untested_objs(module)

winipedia_utils/testing/tests/base/fixtures/scopes/session.py

@@ -16,7 +16,7 @@ from winipedia_utils.modules.package import (
     walk_package,
 )
 from winipedia_utils.projects.poetry.config import (
-    PyProjectTomlConfig,
+    PyprojectConfigFile,
 )
 from winipedia_utils.testing.assertions import assert_with_msg
 from winipedia_utils.testing.convention import (
@@ -39,15 +39,14 @@ def assert_dev_dependencies_config_is_correct() -> None:
         AssertionError: If the dev dependencies in consts.py are not correct
 
     """
-    config = PyProjectTomlConfig()
-    if config.get_package_name() != winipedia_utils.__name__:
+    if PyprojectConfigFile.get_package_name() != winipedia_utils.__name__:
         # this const is only used in winipedia_utils
         # to be able to install them with setup.py
         return
-    actual_dev_dependencies = config.get_dev_dependencies()
-    expected_dev_dependencies = config.get_configs()["tool"]["poetry"]["group"]["dev"][
-        "dependencies"
-    ].keys()
+    actual_dev_dependencies = PyprojectConfigFile.get_dev_dependencies()
+    expected_dev_dependencies = PyprojectConfigFile.get_configs()["tool"]["poetry"][
+        "group"
+    ]["dev"]["dependencies"].keys()
     assert_with_msg(
         set(actual_dev_dependencies) == set(expected_dev_dependencies),
         "Dev dependencies in consts.py are not correct",
@@ -123,7 +122,7 @@ def assert_src_package_correctly_named() -> None:
 
     """
     src_package = get_src_package().__name__
-    config = PyProjectTomlConfig()
+    config = PyprojectConfigFile()
     expected_package = config.get_package_name()
     assert_with_msg(
         src_package == expected_package,

winipedia_utils/testing/tests/base/utils/utils.py

@@ -9,19 +9,29 @@ Returns:
 
 """
 
+import os
 from collections.abc import Callable
 from types import ModuleType
 from typing import Any
 
+from winipedia_utils.logging.logger import get_logger
 from winipedia_utils.modules.function import is_abstractmethod
-from winipedia_utils.modules.module import get_objs_from_obj, make_obj_importpath
+from winipedia_utils.modules.module import (
+    get_objs_from_obj,
+    import_obj_from_importpath,
+    make_obj_importpath,
+    to_module_name,
+)
 from winipedia_utils.testing.assertions import assert_with_msg
+from winipedia_utils.testing.config import LocalSecretsConfigFile
 from winipedia_utils.testing.convention import (
     get_obj_from_test_obj,
     make_test_obj_importpath_from_obj,
     make_untested_summary_error_msg,
 )
 
+logger = get_logger(__name__)
+
 
 def assert_no_untested_objs(
     test_obj: ModuleType | type | Callable[..., Any],
@@ -42,7 +52,15 @@ def assert_no_untested_objs(
     test_objs = get_objs_from_obj(test_obj)
     test_objs_paths = {make_obj_importpath(o) for o in test_objs}
 
-    obj = get_obj_from_test_obj(test_obj)
+    try:
+        obj = get_obj_from_test_obj(test_obj)
+    except ImportError:
+        if isinstance(test_obj, ModuleType):
+            # we skip if module not found bc that means it has custom tests
+            # and is not part of the mirrored structure
+            logger.warning("No source module found for %s, skipping", test_obj)
+            return
+        raise
     objs = get_objs_from_obj(obj)
     supposed_test_objs_paths = {make_test_obj_importpath_from_obj(o) for o in objs}
 
@@ -65,3 +83,26 @@ def assert_isabstrct_method(method: Any) -> None:
         is_abstractmethod(method),
         f"Expected {method} to be abstract method",
     )
+
+
+def get_github_repo_token() -> str:
+    """Get the GitHub token."""
+    # try os env first
+    token = os.getenv("REPO_TOKEN")
+    if token:
+        return token
+
+    local_secrets_module_path = to_module_name(LocalSecretsConfigFile.get_path())
+    local_secrets_module = import_obj_from_importpath(local_secrets_module_path)
+    token = getattr(local_secrets_module, "REPO_TOKEN", None)
+    if not isinstance(token, str):
+        msg = f"Expected REPO_TOKEN to be str, got {type(token)}"
+        raise TypeError(msg)
+    if token:
+        return token
+
+    msg = (
+        f"No token named REPO_TOKEN found "
+        f"in github secrets or {LocalSecretsConfigFile.get_path()}"
+    )
+    raise ValueError(msg)

winipedia_utils/text/config.py

@@ -1,5 +1,6 @@
 """Base class for config files."""
 
+import inspect
 from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import Any
@@ -13,53 +14,80 @@ from winipedia_utils.modules.class_ import init_all_nonabstract_subclasses
 from winipedia_utils.projects.poetry.poetry import (
     get_python_module_script,
 )
+from winipedia_utils.text.string import split_on_uppercase
 
 
 class ConfigFile(ABC):
     """Base class for config files."""
 
+    @classmethod
     @abstractmethod
-    def get_path(self) -> Path:
+    def get_parent_path(cls) -> Path:
         """Get the path to the config file."""
 
+    @classmethod
     @abstractmethod
-    def load(self) -> dict[str, Any]:
+    def load(cls) -> dict[str, Any] | list[Any]:
         """Load the config file."""
 
+    @classmethod
     @abstractmethod
-    def dump(self, config: dict[str, Any]) -> None:
+    def dump(cls, config: dict[str, Any] | list[Any]) -> None:
         """Dump the config file."""
 
+    @classmethod
     @abstractmethod
-    def get_configs(self) -> dict[str, Any]:
+    def get_file_extension(cls) -> str:
+        """Get the file extension of the config file."""
+
+    @classmethod
+    @abstractmethod
+    def get_configs(cls) -> dict[str, Any] | list[Any]:
         """Get the config."""
 
     def __init__(self) -> None:
         """Initialize the config file."""
-        self.path = self.get_path()
-        self.path.parent.mkdir(parents=True, exist_ok=True)
-        if not self.path.exists():
-            self.path.touch()
+        self.get_path().parent.mkdir(parents=True, exist_ok=True)
+        if not self.get_path().exists():
+            self.get_path().touch()
             self.dump(self.get_configs())
 
         if not self.is_correct():
             config = self.add_missing_configs()
             self.dump(config)
 
-        self.config = self.load()
         if not self.is_correct():
-            msg = f"Config file {self.path} is not correct."
+            msg = f"Config file {self.get_path()} is not correct."
             raise ValueError(msg)
 
-    def add_missing_configs(self) -> dict[str, Any]:
+    @classmethod
+    def get_path(cls) -> Path:
+        """Get the path to the config file."""
+        return (
+            cls.get_parent_path() / f"{cls.get_filename()}.{cls.get_file_extension()}"
+        )
+
+    @classmethod
+    def get_filename(cls) -> str:
+        """Get the filename of the config file."""
+        name = cls.__name__
+        abstract_parents = [
+            parent.__name__ for parent in cls.__mro__ if inspect.isabstract(parent)
+        ]
+        for parent in abstract_parents:
+            name = name.removesuffix(parent)
+        return "_".join(split_on_uppercase(name)).lower()
+
+    @classmethod
+    def add_missing_configs(cls) -> dict[str, Any] | list[Any]:
         """Add any missing configs to the config file."""
-        current_config = self.load()
-        expected_config = self.get_configs()
+        current_config = cls.load()
+        expected_config = cls.get_configs()
         nested_structure_is_subset(
             expected_config,
             current_config,
-            self.add_missing_dict_val,
-            self.insert_missing_list_val,
+            cls.add_missing_dict_val,
+            cls.insert_missing_list_val,
         )
         return current_config
 
@@ -77,28 +105,30 @@ class ConfigFile(ABC):
         """Append a missing list value."""
         actual_list.insert(index, expected_list[index])
 
-    def is_correct(self) -> bool:
+    @classmethod
+    def is_correct(cls) -> bool:
         """Check if the config is correct.
 
         If the file is empty, it is considered correct.
         This is so bc if a user does not want a specific config file,
         they can just make it empty and the tests will not fail.
         """
-        return self.is_unwanted() or self.is_correct_recursively(
-            self.get_configs(), self.load()
+        return cls.is_unwanted() or cls.is_correct_recursively(
+            cls.get_configs(), cls.load()
         )
 
-    def is_unwanted(self) -> bool:
+    @classmethod
+    def is_unwanted(cls) -> bool:
         """Check if the config file is unwanted.
 
         If the file is empty, it is considered unwanted.
         """
-        return self.path.exists() and self.path.read_text() == ""
+        return cls.get_path().exists() and cls.get_path().read_text() == ""
 
     @staticmethod
     def is_correct_recursively(
-        expected_config: Any,
-        actual_config: Any,
+        expected_config: dict[str, Any] | list[Any],
+        actual_config: dict[str, Any] | list[Any],
     ) -> bool:
         """Check if the config is correct.
 
@@ -119,35 +149,52 @@ class ConfigFile(ABC):
         """Initialize all subclasses."""
         init_all_nonabstract_subclasses(cls, load_package_before=winipedia_utils)
 
+    @staticmethod
+    def get_python_setup_script() -> str:
+        """Get the poetry run setup script."""
+        from winipedia_utils import setup  # noqa: PLC0415  # avoid circular import
+
+        return get_python_module_script(setup)
+
 
 class YamlConfigFile(ConfigFile):
     """Base class for yaml config files."""
 
-    def load(self) -> dict[str, Any]:
+    @classmethod
+    def load(cls) -> dict[str, Any] | list[Any]:
         """Load the config file."""
-        return yaml.safe_load(self.path.read_text()) or {}
+        return yaml.safe_load(cls.get_path().read_text()) or {}
 
-    def dump(self, config: dict[str, Any]) -> None:
+    @classmethod
+    def dump(cls, config: dict[str, Any] | list[Any]) -> None:
         """Dump the config file."""
-        with self.path.open("w") as f:
+        with cls.get_path().open("w") as f:
             yaml.safe_dump(config, f, sort_keys=False)
 
-    @staticmethod
-    def get_python_setup_script() -> str:
-        """Get the poetry run setup script."""
-        from winipedia_utils import setup  # noqa: PLC0415  # avoid circular import
-
-        return get_python_module_script(setup)
+    @classmethod
+    def get_file_extension(cls) -> str:
+        """Get the file extension of the config file."""
+        return "yaml"
 
 
 class TomlConfigFile(ConfigFile):
     """Base class for toml config files."""
 
-    def load(self) -> dict[str, Any]:
+    @classmethod
+    def load(cls) -> dict[str, Any]:
         """Load the config file."""
-        return tomlkit.parse(self.path.read_text())
+        return tomlkit.parse(cls.get_path().read_text())
 
-    def dump(self, config: dict[str, Any]) -> None:
+    @classmethod
+    def dump(cls, config: dict[str, Any] | list[Any]) -> None:
         """Dump the config file."""
-        with self.path.open("w") as f:
-            tomlkit.dump(config, f)
+        if not isinstance(config, dict):
+            msg = f"Cannot dump {config} to toml file."
+            raise TypeError(msg)
+        with cls.get_path().open("w") as f:
+            tomlkit.dump(config, f, sort_keys=False)
+
+    @classmethod
+    def get_file_extension(cls) -> str:
+        """Get the file extension of the config file."""
+        return "toml"

{winipedia_utils-0.3.43.dist-info → winipedia_utils-0.4.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: winipedia-utils
-Version: 0.3.43
+Version: 0.4.18
 Summary: A package with many utility functions
 License-Expression: MIT
 License-File: LICENSE
@@ -16,6 +16,7 @@ Requires-Dist: defusedxml
 Requires-Dist: keyring
 Requires-Dist: pathspec
 Requires-Dist: polars
+Requires-Dist: pygithub
 Requires-Dist: pyyaml
 Requires-Dist: setuptools
 Requires-Dist: tomlkit
@@ -62,13 +63,26 @@ A comprehensive Python utility package that enforces best practices, automates p
 
 ## Quick Start
 
-### Installation
+### How to setup a new project
 
 ```bash
-# Add winipedia-utils to your project
+# 1: Create a new repository on GitHub
+# The default branch must be called main
+# add a PAT or Fine-Grained Access Token to your repo secrets called REPO_TOKEN that has write access to the repository (Adminstration and Contents)(needed for branch protection in health_check.yaml - see winipedia_utils.git.github.repo.protect and for commiting as an action in release.yaml)
+
+# 2: Clone the repository
+git clone https://github.com/owner/repo.git
+
+# 3: Create a new poetry project
+poetry init # or poetry new
+# 4: Poetry will ask you some stuff when you run poetry init.
+# First author name must be equal to the GitHub repository owner (username).
+# The repository name must be equal to the package/project name.
+
+# 5: Add winipedia-utils to your project
 poetry add winipedia-utils
 
-# Run the automated setup
+# 6: Run the automated setup
 poetry run python -m winipedia_utils.setup
 ```
 
@@ -88,8 +102,9 @@ The setup creates the following configuration files:
 - `.pre-commit-config.yaml` - Pre-commit hook configuration
 - `.gitignore` - Git ignore rules (assumes you added one on GitHub before.)
 - `pyproject.toml` - Project configuration with Poetry settings
-- `.github/workflows/release.yaml` - Release workflow (Creates a release on GitHub when oushing to main)
-- `.github/workflows/publish.yaml` - Publishing workflow (Publishes to PyPI when a release is created by the release workflow)
+- `.github/workflows/health_check.yaml` - Health check workflow (Runs on every push and pull request)
+- `.github/workflows/release.yaml` - Release workflow (Creates a release on GitHub when the same actions as in health check pass and commits are pushed to main)
+- `.github/workflows/publish.yaml` - Publishing workflow (Publishes to PyPI when a release is created by the release workflow, if you use this workflow, you need to add a PYPI_TOKEN (named PYPI_TOKEN) to your GitHub secrets that has write access to the package on PyPI.)
 - `py.typed` - PEP 561 marker for type hints
 - `experiment.py` - For experimentation (ignored by git)
 - `test0.py` - Test file with one empyt test (so that initial tests pass)
@@ -106,8 +121,8 @@ Usually VSCode or other IDEs activates the venv automatically when opening the t
 1. Patch version (poetry version patch)
 2. Add version patch to git (git add pyproject.toml)
 3. Update package manager (poetry self update)
-4. Install packages (poetry install)
-5. Update packages (poetry update)
+4. Install packages (poetry install --with dev)
+5. Update packages (poetry update --with dev (winipedia_utils forces all dependencies with * to be updated to latest compatible version))
 6. Lock dependencies (poetry lock)
 7. Check package manager configs (poetry check --strict)
 8. Create tests (python -m winipedia_utils.testing.create_tests)