Skip to main content

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 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

  • RepresentationImplementation: Base architecture for recursive representations (defaults to standard repr)

  • GreprRepresentationImplementation: Built-in grepr style implementation with override hooks

  • GEnum: Enum base class with concise Class.Member repr

  • GreprDataclassImplementation: Class-based architecture behind grepr_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)

Source distribution for gceutils 1.1.1
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)

Table of built distributions (wheels) for gceutils 1.1.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page