split off from py-pmp-manip; prepared first release

Author: GermanCodeEngineer

.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish Python package
+
+on:
+  push:
+    tags:
+      - "v*.*.*"   # only run when you push a version tag
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        run: twine upload dist/*
+        env:
+          TWINE_USERNAME: "__token__"
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+gen_ext_opcode_info/
+.coverage
+.pytest_cache/
+htmlcov/
+dist/
+*.egg-info/
+build/

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

LICENSE

@@ -0,0 +1,145 @@
+<div align="center">
+
+# gceutils
+
+Python utilities for DRY tools, rich repr/validation helpers,  object-tree iteration & more.
+
+</div>
+
+---
+
+## Features
+
+The public API is kept intentionally small. Highlights:
+
+- `grepr_dataclass`, `field`: Enhanced dataclasses with validation and improved representation
+- `HasGreprValidate`: Protocol reflecting the effects of `grepr_dataclass`
+- `AbstractTreePath`: Path abstraction for nested object trees (attributes, indexes, keys)
+- `NotSet`, `NotSetType`: Unique sentinel useful for keyword arguments and defaults
+- `enforce_argument_types`: Runtime enforcement of function argument types from annotations
+- `enforce_type`: Recursive type checking against rich typing constructs
+- `DualKeyDict`: Dictionary supporting two linked key spaces with full mapping features
+- `GU_PathValidationError`: Validation error carrying an `AbstractTreePath` context
+
+- `read_all_files_of_zip`: Read all files from a ZIP into a name→bytes map (with robust errors)
+- `read_file_text`: Read text files with encoding and solid error reporting
+- `write_file_text`: Write text files with encoding and solid error reporting
+- `delete_file`: Remove a file with clear, specific exceptions
+- `delete_directory`: Recursively remove a directory with clear, specific exceptions
+- `create_zip_file`: Build a ZIP file from an in-memory name→bytes mapping
+- `file_exists`: Lightweight existence check for a path
+
+- `KeyReprDict`: Dict wrapper whose repr displays only keys
+- `grepr`: Flexible pretty-printer for dataclasses, collections, dicts, and `DualKeyDict`
+- `GEnum`: Enum base class with concise `Class.Member` repr
+
+- `TreeVisitor`: Recursive traversal over dataclass-based object trees with type filtering
+
+- `ValidateAttribute`: Prebuilt validators (type/range/length/formats)
+- `is_valid_js_data_uri`: Validate JS data URIs
+- `is_valid_directory_path`: Validate an existing or creatable, writable directory path
+- `is_valid_url`: Validate basic HTTP(S) URLs with a domain
+
+For the full, always-up-to-date list, see [features.md](features.md).
+
+---
+
+## Install
+
+Python 3.12+ is required.
+
+- From PyPI (if published):
+
+```bash
+pip install gceutils
+```
+
+- From source (editable):
+
+```bash
+git clone https://github.com/GermanCodeEngineer/gceutils.git
+cd gceutils
+pip install -e .
+```
+
+---
+
+## Quick Examples
+
+Validate attributes using built-in validators:
+
+```python
+from gceutils import grepr_dataclass, ValidateAttribute as VA, AbstractTreePath, HasGreprValidate
+from datetime import date
+
+@grepr_dataclass()
+class Config(HasGreprValidate): # HasGreprValidate is optional, just helps type checkers
+	color: str
+
+	def post_validate(self, path: AbstractTreePath) -> None:
+		# Additional validation can be done here if needed
+		if date.today().weekday() == 1:
+			VA.VA_HEX_COLOR(self, path, "color", condition="on mondays")
+
+cfg = Config(color="#FF0956e") # not valid
+cfg.validate(path=AbstractTreePath(())) # Ensures color is a str and hex color
+```
+Output(abbreviated):
+```
+gceutils.errors.GU_InvalidValueError: on tuesdays: color of a __main__.Config must be a valid hex color eg. '#FF0956'
+```
+
+Traverse an object tree and collect specific node types:
+
+```python
+from gceutils import grepr_dataclass, grepr, TreeVisitor
+
+@grepr_dataclass()
+class Node:
+	name: str
+	children: list["Node"]
+
+root = Node("root", [Node("a", []), Node("b", [])])
+visitor = TreeVisitor.create_new_include_only([Node])
+matches = visitor.visit_tree(root)  # {AbstractTreePath: Node}
+print("My matches:", grepr(matches))
+```
+Output:
+```
+My matches: {
+    AbstractTreePath(.children[0]): Node(name="a", children=[]),
+    AbstractTreePath(.children[1]): Node(name="b", children=[]),
+}
+```
+
+Read all files from a ZIP and pretty-print a structure:
+
+```python
+from gceutils import read_all_files_of_zip, grepr
+
+contents = read_all_files_of_zip("archive.zip")  # {"path/inside.txt": b"..."}
+print(grepr(list(contents.keys()), indent=2))
+```
+
+---
+
+## Testing
+
+This repo uses `pytest`.
+
+```bash
+pytest
+```
+
+---
+
+## Contributing
+
+Contribution is welcomed and encouraged.
+
+---
+
+## License
+
+GPL-3.0-or-later — see [LICENSE](LICENSE).
+

README.md

@@ -0,0 +1,18 @@
+TODOs Sorted by Priorites
+
+Currently Working On: /
+
+Changelog since last Release: /
+
+High: /
+
+Medium:
+    - S: fix grepr multiline string issue
+        => also fix parent and subclass field order issue
+    - S: investigate custom type object variables(example: vector extension)
+
+Low:
+    - M: replace remaining io actions with wrappers (eg. file_exists instead of os.path.exists)
+    - S: move from os.path to pathlib
+
+Formatting: /

TODO.txt

@@ -0,0 +1,6 @@
+import sys
+from pathlib import Path
+
+# Add src directory to Python path for tests
+src_path = Path(__file__).parent / "src"
+sys.path.insert(0, str(src_path))

conftest.py

@@ -0,0 +1,71 @@
+# Preparing a New Release
+
+### **1. Core Functionality**
+
+* ✅ All planned features for the initial release should be implemented.
+* ✅ Features should work as expected; no critical bugs that break core functionality.
+* ✅ Edge cases and error handling should be covered.
+
+---
+
+### **2. Code Quality**
+
+* ✅ Code is clean, readable, and follows PEP 8 style conventions.
+* ✅ Functions and classes are well-organized; modular design.
+* ✅ Unused code, debug prints, and commented-out sections are removed.
+* ✅ Temporary files and file calls are removed.
+* ✅ Proper exception handling is in place.
+
+---
+
+### **3. Testing**
+
+* ✅ Unit tests cover critical functionality.
+* ✅ Optional: Integration tests to ensure components work together.
+* ✅ All tests pass consistently.
+
+---
+
+### **4. Stability & Security**
+
+* ✅ No hard-coded secrets (API keys, passwords) in the repo.
+* ✅ Avoid known security vulnerabilities in dependencies.
+* ✅ Graceful shutdown and resource cleanup (files, network connections).
+
+---
+
+# Next Steps
+1. **Check for dependency updates** to see if newer versions are available:
+    ```bash
+    python -m scripts.check_dependency_updates
+    ```
+2. **Ensure all tests are successful** and generate coverage report:
+    ```bash
+    coverage run -m pytest tests/
+    ```
+    ```bash
+    coverage html
+    ```
+3. View coverage report: **Are all critical code files covered?**
+4. **Review pyproject.toml** with the new dependencies:
+    ```bash
+    python -m scripts.review_pyproject_toml
+    ```
+5. **Follow suggested changes**(except coverage and pipreqs) **and increase version number**
+6. **Build package locally**:
+    ```bash
+    pip install --upgrade build
+    python -m build
+    ```
+7. **Commit and Push all changes** (Just an Example):
+    ```bash
+    git add -A
+    git commit -m "prepare next release"
+    git push
+    ``` 
+8. **Create a Git tag with the version number and Push** the tag to your remote:
+    ```bash
+    git tag v1.2.3
+    git push origin v1.2.3
+    ```
+9. **Verify CI passes on the release tag** (GitHub Actions)

docs/release_tutorial.md

@@ -0,0 +1,46 @@
+[project]
+name = "gceutils"
+version = "1.0.0"
+description = "Python utilities for DRY tools, rich repr/validation helpers, object-tree iteration & more."
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.12"
+license = { text = "GPL-3.0-or-later" }
+authors = [{name = "GermanCodeEngineer", email = "germancodeengineer@proton.me"}]
+
+# sometimes auto generated
+dependencies = []
+
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/GermanCodeEngineer/gceutils/"
+Repository = "https://github.com/GermanCodeEngineer/gceutils/"
+Issues = "https://github.com/GermanCodeEngineer/gceutils/issues/"
+
+# sometimes auto generated
+[project.optional-dependencies]
+dev = [
+    "Requests~=2.32",
+    "pytest~=9.0",
+    "tomlkit~=0.14",
+    "coverage~=7.13",
+    "pipreqs~=0.4",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["gceutils*"]
+
+[tool.setuptools]
+include-package-data = true