gceutils
Python utilities for DRY tools, rich repr/validation helpers, object-tree iteration & more.
Features
The public API is kept intentionally small. Highlights:
-
grepr_dataclass,field: Enhanced dataclasses with validation and improved representation -
HasGreprValidate: Protocol reflecting the effects ofgrepr_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 anAbstractTreePathcontext -
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, andDualKeyDict -
RepresentationImplementation: Base architecture for recursive representations (defaults to standardrepr) -
GreprRepresentationImplementation: Built-ingreprstyle implementation with override hooks -
GEnum: Enum base class with conciseClass.Memberrepr -
GreprDataclassImplementation: Class-based architecture behindgrepr_dataclass -
grepr_dataclass(..., repr_implementation=...): Provide a custom representation implementation class -
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.
Install
Python 3.12+ is required.
- From PyPI:
pip install gceutils
- From source (editable):
git clone https://github.com/GermanCodeEngineer/gceutils.git
cd gceutils
pip install -e .
Quick Examples
Validate attributes using built-in validators:
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:
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:
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))
Customize representation behavior with implementation classes:
from gceutils import (
RepresentationImplementation,
GreprRepresentationImplementation,
GreprDataclassImplementation,
grepr_dataclass,
)
class MyGrepr(GreprRepresentationImplementation):
# Optional: customize special-case formatting.
def implement_special_cases(self, obj, level, path=None):
if isinstance(obj, bytes):
return f"<bytes:{len(obj)}>"
return NotImplemented
@grepr_dataclass(repr_implementation=MyGrepr)
class Payload:
data: bytes
print(repr(Payload(data=b"abc")))
# Payload(data=<bytes:3>)
You can also use GreprDataclassImplementation directly if you want to extend how
the decorator composes dataclass, repr, and validate behavior.
Testing
This repo uses pytest.
pytest
Contributing
Contribution is welcomed and encouraged.
License
GPL-3.0-or-later — see LICENSE.
Metadata
Release files for gceutils 1.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gceutils-1.1.1.tar.gz | 36.7 kB | Without provenance | Details for gceutils-1.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gceutils-1.1.1-py3-none-any.whl | Python 3 | none | any | Details for gceutils-1.1.1-py3-none-any.whl |
Total release size: 74.0 kB
Release files / gceutils-1.1.1.tar.gz
| Download URL | gceutils-1.1.1.tar.gz |
|---|---|
| Size | 36.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e0d59c79f37e1775cb773a63abeeadacb39d09325a3a0615ebd014033b550bb9
|
|
BLAKE2b-256 checksum How to use checksums |
fe3246ad05d8420e0d880c3a39cdff116c0a5e176ed74d503d3dc6cd9bf61f67
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.5
|
Release files / gceutils-1.1.1-py3-none-any.whl
| Download URL | gceutils-1.1.1-py3-none-any.whl |
|---|---|
| Size | 37.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cbc6ec49cfd53a0c9c945d34fcc5cbf54dd6a4f5351409bf854712392ac5332b
|
|
BLAKE2b-256 checksum How to use checksums |
0df6635e10c7ae17eeec3fcb272e2b0596192cadc595439121156f16455f7b55
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.5
|
Security for gceutils 1.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.